home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1991 …esperately Seeking Seven / Desperately Seeking Seven.2mg / Dev.CD.8 / Essentials / Tools / Technical.Notes / IIGS / TN.IIGS.024 < prev    next >
Encoding:
Text File  |  1991-05-28  |  10.2 KB  |  256 lines  |  [04] ASCII Text (0x0000)
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. Apple IIgs
  7. #24:         Apple IIgs Toolbox Reference Updates
  8.  
  9. Revised by:  Dave Lyons                                             July 1991
  10. Written by:    Rilla Reynolds, Matt Deatherage, Dave Lyons,
  11.                C.K. Haun & Eric Soldan                           October 1987
  12.  
  13. This Technical Note documents changes to the Apple IIgs Toolbox Reference 
  14. manuals.  Please contact Apple II Developer Technical Support at the address 
  15. listed in Apple II Technical Note #0 if you have additional corrections or 
  16. suggestions for any of the Apple IIgs Toolbox documentation.
  17.  
  18. Changes since March 1991:  Added corrections to Volume 2, Tool Locator, 
  19. Window Manager, and Appendix A.  Added corrections to Volume 3, List Manager, 
  20. Memory Manager, Menu Manager, and the rTextForLETextBox2 resource format.  
  21. Rearranged Volume 3 corrections to put them in order.
  22. _____________________________________________________________________________
  23.  
  24. The current Apple IIgs Toolbox reference material is Apple IIgs Toolbox 
  25. Reference, volumes 1 to 3 as well as this Technical Note.  (The Apple IIgs 
  26. Toolbox Reference Update beta draft from APDA is obsolete and should not be 
  27. used.)
  28.  
  29. Corrections to Volume 1
  30.  
  31. FixAppleMenu Can Die With Error $0512
  32.  
  33. Fatal system error $0512 comes from FixAppleMenu (in the Desk Manager).  It 
  34. means that one of your installed New Desk Accessories does not have a 
  35. well-formed menu title string.  In particular, the required backslash (\) 
  36. character was not found (make sure bit seven is off).
  37.  
  38. DeleteMItem Operates on the Current Menu Bar
  39.  
  40. Page 13-37 says DeleteMItem removes the specified item from the current menu.  
  41. It means the item is removed from the current menu bar.
  42.  
  43. The List Manager Wants the Port Set Properly
  44.  
  45. The List Manager expects the current grafPort to be set properly before you 
  46. make most List Manager calls; drawing can occur in funny places if the 
  47. grafPort is not set properly before calls that draw (like SelectMember2).  
  48. Most List Manager calls, and many other toolbox calls, require that the 
  49. current grafPort be explicitly set.  Before you call List Manager routines 
  50. that draw, set the current port to your window with a SetPort call.  Remember 
  51. the note in Volume 2 under the NewWindow call--"Important:  NewWindow does 
  52. not set the current port, but many routines require that a current port 
  53. exist.  Use the QuickDraw II routine SetPort to set the current port."  Using 
  54. SetPort can prevent toolbox confusion and reduce your debugging time.
  55.  
  56. Error $0F02 from GetMItem
  57.  
  58. GetMItem returns error $0F02 if the specified menu item is not found.
  59.  
  60. ReadAsciiTime Result Buffer
  61.  
  62. The description of ReadAsciiTime (in the Miscellaneous Tools) on page 14-16 
  63. should say the most significant bit (not byte) of each character is set to 
  64. one.
  65.  
  66. SystemEvent Is All Backwards
  67.  
  68. Although applications still should not call SystemEvent, we should note for 
  69. completeness that the input parameters listed in Volume 1 are exactly 
  70. backwards in the stack diagram.
  71.  
  72.  
  73. Corrections to Volume 2
  74.  
  75. QuickDraw Auxiliary Error Codes
  76.  
  77. Following are some error codes from QuickDraw Auxiliary that are not listed 
  78. in volume 2.
  79.  
  80.     $1210: picEmpty
  81.     $1211: picAlreadyOpen
  82.     $1212: pictureError
  83.  
  84.     $1221: badRect
  85.     $1222: badMode
  86.  
  87. FrameRgn Does Not Contribute to an Open Region
  88.  
  89. The description of the FrameRgn routine on page 16-105 in the Apple IIgs 
  90. Toolbox Reference, Volume 2 states that FrameRgn will contribute to a region 
  91. definition if a region is open when FrameRgn is called.  This is incorrect; 
  92. FrameRgn does not contribute to the region being defined.  To add a region to 
  93. another region, use XorRgn or UnionRgn.
  94.  
  95. Tool Locator, TLMountVolume
  96.  
  97. On page 24-21, the description of TLMountVolume does not bother to mention 
  98. that QuickDrawJII and Event Manager must be active.  If they are not, you 
  99. should use TLTextMountVolume instead.
  100.  
  101. Window Manager, "Draw Information Bar Routine"
  102.  
  103. On page 25-23, the code to clean up the stack is incorrect.  On the sta <14, 
  104. the comment "Works because stack and direct page are equal" is no longer 
  105. true--they were equal until the PLY two lines earlier.  One way to correct 
  106. the code is to replace sta <14 with sta 14,s and sta <12 with sta 12,s.
  107.  
  108. Window Manager, InvalRect
  109.  
  110. The description of InvalRect on page 25-80 claims that InvalRect modifies the 
  111. input rectangle; the rectangle is actually not modified.
  112.  
  113. Window Manager, SetZoomRect
  114.  
  115. The description of SetZoomRect on page 25-112 refers to fZoomed as bit 2 in 
  116. the window frame.  fZoomed is actually bit 1, with value $0002.
  117.  
  118. Appendix A, "Writing Your Own Tool Sets"
  119.  
  120. At the bottom of page A-8, "lda #$90" should read "lda #$8100" for version 
  121. 1.0 prototype.
  122.  
  123. On page A-10, the figure should show two RTL addresses (6 bytes) on the 
  124. stack.
  125.  
  126.  
  127. Corrections to Volume 3
  128.  
  129. Control Manager:  Menu Events
  130.  
  131. On page 28-15, note that a Menu Event is identified by the value wInSpecial 
  132. ($0019) in the what field of the task record.  The menu item ID is in the low 
  133. word of the wmTaskData field.
  134.  
  135. In the Draw routine for both extended and non-extended controls, the high 
  136. word of ctlParam (which was previously undefined) contains a flag which the 
  137. definition procedure can use to draw a normal or dimmed control.  The value 
  138. is $0000 normally, but it is $FFFF when the control is inactive (hilite value 
  139. equals $00FF), or when the control's state is tied to the window's state and 
  140. the window is inactive.
  141.  
  142. Desk Manager:  Errors from AddToRunQ and RemoveFromRunQ
  143.  
  144. The Desk Manager chapter, page 29-6, states no errors are possible for 
  145. AddToRunQ, but any errors from the Miscellaneous Tools routine AddToQueue are 
  146. returned unchanged.
  147.  
  148. Page 29-8 states no errors are possible from RemoveFromRunQ, but any errors 
  149. from DeleteFromQueue are returned unchanged.
  150.  
  151. Event Manager:  What SetAutoKeyLimit Really Does
  152.  
  153. Page 31-6 says that PostEvent will add up to the new auto-key limit number of 
  154. auto-key events before reverting to the rule that auto-key events are only to 
  155. be posted if the event queue is empty.  This is not quite right.  Actually, 
  156. the parameter to SetAutoKeyLimit is used in a size comparison on the event 
  157. queue--if there are newLimit or more events in the queue, auto-key events 
  158. will not be posted.  Volume 3 incorrectly states that up to newLimit auto-key 
  159. events will be posted; this is only true if you assume the event queue is 
  160. empty before the first auto-key event comes in.
  161.  
  162. List Manager
  163.  
  164. On page 35-9, the description of ResetMember2 does not point out an important 
  165. difference between ResetMember2 and NextMember2.  ResetMember2 deselects the 
  166. member found, but NextMember2 does not change the member's status.
  167.  
  168. On page 35-3, bit 5 of the memFlag field is defined--it makes an item 
  169. inactive.  To make use of this bit, you must also set bit 6 of the List 
  170. control's ctlFlag field; if you don't set this bit, the user will still be 
  171. able to select members using the mouse.
  172.  
  173. Memory Manager
  174.  
  175. If the Memory Manager detects a corrupted entry in the Out Of Memory Queue, 
  176. fatal system error $0209 occurs.
  177.  
  178. Menu Manager
  179.  
  180. On page 28-65, the description of the initialValue field is misleading.  
  181. Cross out the text "that is, its relative position within the array of items 
  182. for the menu."  initialValue is simply a menu item ID, not an offset into an 
  183. array.
  184.  
  185. Miscellaneous Tools:  Interrupt State Record Not Always Complete
  186.  
  187. The interrupt state record returned from GetInterruptState (and passed to 
  188. SetInterruptState) is not always completely filled in.  The Interrupt 
  189. Manager, in the interest of serving AppleTalk and serial interrupts as 
  190. rapidly as possible, does not take the time to save all the items in the 
  191. record until those timing-critical interrupt handlers have been called.  Some 
  192. items are not saved at all unless the interrupt is determined to be a BRK 
  193. instruction.  The following table shows all items in the current interrupt 
  194. state record and when they become valid:
  195.  
  196. Record variable    When valid
  197. ----------------------------------
  198. irq_A              always
  199. irq_X              always
  200. irq_Y              always
  201. irq_S              after serial
  202. irq_D              always
  203. irq_P              only on break
  204. irq_DB             after serial
  205. irq_e              after serial
  206. irq_K              only on break
  207. irq_PC             only on break
  208. irq_state          after serial
  209. irq_shadow         always
  210. irq_mslot          after serial
  211. ----------------------------------
  212.  
  213. Table 1--Validity of Interrupt Record
  214.  
  215.  
  216. Tool Locator:  Notes on StartUpTools
  217.  
  218. StartUpTools in System Software 5.0.4 and earlier is intended to be used from 
  219. applications only, not from NDAs.
  220.  
  221. The order of the toolArray entries in the StartStop record is not important.  
  222. StartUpTools and ShutDownTools always start up and shut down tools in a 
  223. correct order.
  224.  
  225. StartUpTools in System Software 5.0.4 and earlier fails to open your 
  226. application's resource fork if the application's filename contains a slash 
  227. (/) or if the application directory path is longer than 64 characters.
  228.  
  229. For maximum compatibility, pass your application's master user ID with any 
  230. auxID to StartUpTools instead of allocating a new user ID.
  231.  
  232. Window Manager:NewWindow2 Parameters Override Template Even When You Pass NIL
  233.  
  234. The description of the NewWindow2 call on page 52-32 is in error.  The 
  235. description of the titlePtr, refCon, contentDrawPtr, and defProcPtr says, "To 
  236. prevent NewWindow2 from replacing the template values, supply NIL 
  237. pointers..."  This is only  true for the titlePtr parameter--if you pass NIL 
  238. for any of the other parameters then the value of that parameter in your 
  239. window record is also NIL, no matter what the template value was.  In other 
  240. words, if you have the value $99 stored in your template refCon field, and 
  241. you pass NIL for the refCon value in a NewWindow2 call, the value of the 
  242. refCon in the returned grafPortPtr is NIL.
  243.  
  244. Appendix E:  rTextForLETextBox2 Resources
  245.  
  246. Page E-68 of Volume 3 shows a length field at the beginning of an 
  247. rTextForLETextBox2 resource. This field is not actually present.  The length 
  248. is simply the size of the resource--it is not stored redundantly.
  249.  
  250.  
  251.  
  252. Further Reference
  253. _____________________________________________________________________________
  254.   o  Apple IIgs Toolbox Reference, Volumes 1-3
  255.  
  256.